/*
 * Copyright (c) 2010 Curtis Boyden.  All rights reserved. 
 * This software was developed by Curtis Boyden and is provided under the terms 
 * of the GNU Lesser General Public License, Version 2.1. You may not use 
 * this file except in compliance with the license. If you need a copy of the license, 
 * please go to http://www.gnu.org/licenses/lgpl-2.1.txt. The Original Code is ejMud
 * (Ewerp Java MUD).  The Initial Developer is Curtis Boyden.
 *
 * Software distributed under the GNU Lesser Public License is distributed on an "AS IS" 
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or  implied. Please refer to 
 * the license for the specific language governing your rights and limitations.
 */

package com.ewerp.server.plugins;



/**
 * The {@link IPluginManager} is the heart of the ejMud. All services register
 * themselves as plugins with the {@link IPluginManager} and query the
 * {@link IPluginManager} for services they require themselves.
 * 
 * @author cboyden
 * 
 */
public interface IPluginManager {

    /**
     * Request an {@link IPlugin} that implements the {@link Class} for a given
     * namespace. The {@link IPlugin} provides functionality to the other
     * {@link IPlugin}s.
     * 
     * @param namespace
     *            May be specified to prevent collision <br />
     *            <ul>
     *            <li>String : Any valid string can be used to represent a
     *            namespace</li>
     *            <li>null : Use the default namespace</li>
     *            </ul>
     * @param clazz
     *            The interface implemented by the {@link IPlugin} that is being
     *            requested <br />
     *            <ul>
     *            <li>{@link Class} : A valid {@link Class} representing the
     *            desired functionality to retrieve</li>
     *            <li>null : A null value will result in an
     *            {@link IllegalArgumentException}</li>
     *            </ul>
     * @return An instance of {@link IPlugin} that implements the interface
     *         requested by the clazz parameter <br />
     *         Null if no matching {@link IPlugin} can be found
     * @throws IllegalArgumentException
     *             Must be thrown if clazz is null
     */
    public IPlugin getPlugin(String namespace, Class<?> clazz) throws IllegalArgumentException;

    /**
     * Request an {@link IPlugin} that implements the {@link Class} using a
     * default namespace. The {@link IPlugin} provides functionality to the
     * other {@link IPlugin}s.
     * 
     * @param clazz
     *            The interface implemented by the {@link IPlugin} that is being
     *            requested <br />
     *            <ul>
     *            <li>{@link Class} : A valid {@link Class} representing the
     *            desired functionality to retrieve</li>
     *            <li>null : A null value will result in an
     *            {@link IllegalArgumentException}</li>
     *            </ul>
     * @return An instance of {@link IPlugin} that implements the interface
     *         requested by the clazz parameter <br />
     *         Null if no matching {@link IPlugin} can be found
     * @throws IllegalArgumentException
     *             Must be thrown if clazz is null
     */
    public IPlugin getPlugin(Class<?> clazz) throws IllegalArgumentException;

    /**
     * Register an {@link IPlugin} associated with a given namespace. The
     * {@link IPlugin} provides functionality to the other {@link IPlugin}s.
     * 
     * @param namespace
     *            May be specified to prevent collision <br />
     *            <ul>
     *            <li>String : Any valid string can be used to represent a
     *            namespace</li>
     *            <li>null : Use the default namespace</li>
     *            </ul>
     * @param plugin
     *            An instance of {@link IPlugin} that provides functionality to
     *            the ejMud <br />
     *            <ul>
     *            <li>{@link IPlugin} : A valid plugin extending {@link IPlugin}
     *            </li>
     *            <li>null : A null value will result in an
     *            {@link IllegalArgumentException}</li>
     *            </ul>
     * @throws IllegalArgumentException
     *             Must be thrown if {@link IPlugin} is null
     */
    public void addPlugin(String namespace, IPlugin plugin) throws IllegalArgumentException;

    /**
     * Register an {@link IPlugin} associated with a given namespace. The
     * {@link IPlugin} provides functionality to the other {@link IPlugin}s.
     * 
     * @param plugin
     *            An instance of {@link IPlugin} that provides functionality to
     *            the ejMud <br />
     *            <ul>
     *            <li>{@link IPlugin} : A valid plugin extending {@link IPlugin}
     *            </li>
     *            <li>null : A null value will result in an
     *            {@link IllegalArgumentException}</li>
     *            </ul>
     * @throws IllegalArgumentException
     *             Must be thrown if {@link IPlugin} is null
     */
    public void addPlugin(IPlugin plugin) throws IllegalArgumentException;
}
